Skip to content

ci(workflows): v1.1.0 — node on self-hosted, annotated guard failures, proven Coolify deploys [FACT-1885] - #2

Merged
practical-bot merged 3 commits into
mainfrom
ci/fact-1885-v1.1.0
Nov 17, 2026
Merged

practical-bot merged 3 commits into
mainfrom
ci/fact-1885-v1.1.0

Conversation

@jcotillo

@jcotillo jcotillo commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Base

This branch starts at v1 (228cab2, the head of #1) and targets main, which still holds only the profile README. Merging it lands #1's commits too, and GitHub then marks #1 merged. v1 is not moved or deleted. After this merges, v1.1.0 is created on the merge commit.

Why

  • The Proxmox self-hosted runners have no node, so pr-guard.yml failed there before its script ran (FACT-1952).
  • pr-guard.yml checked its script out at a hard-coded v1, so a caller of any newer tag still ran v1's script.
  • Those runners lose job logs (FACT-1971). A failure printed only to stderr leaves a red check with no reason.
  • coolify-deploy.yml went green when Coolify accepted the webhook, not when the deploy was live (FACT-1910).

What changed

  • pr-guard.yml sets up Node 22 and checks the script out at job.workflow_sha, the commit of the workflow file that defines the job. For a reusable workflow, that commit is this repository's, not the caller's (GitHub changelog 2026-09-03; the contexts reference documents job.workflow_sha, job.workflow_repository, job.workflow_ref, and job.workflow_file_path). If a runner leaves the value empty, it falls back to v1.1.0 and emits a ::warning::. Each release bumps that fallback.

  • scripts/pr-guard.mjs: every failure goes to stderr and is also emitted as ::error::<msg>. The message is escaped the way GitHub's toolkit does it (%→%25, CR→%0D, LF→%0A).

  • coolify-deploy.yml with the new scripts/coolify-deploy.mjs follows frontdesk's scripts/ci/deploy-coolify.mjs:

    1. Posts the webhook and writes deployment-uuid.
    2. Polls GET <webhook origin>/api/v1/deployments/<uuid> with the same bearer token every 10s until finished. failed, cancelled, or cancelled-by-user fails the job. A 4xx fails at once. A 5xx or network drop is retried up to 6 times in a row.
    3. With the new optional inputs health-url + expected-version, polls the URL until its body contains the version.

    All three steps share timeout-minutes minus 1 minute, so a timeout fails with a named ::error:: instead of the job being killed. The webhook URL and token are ::add-mask::ed, and error text names only path and status, never a body. The token is now required, because the status polls need it. No caller uses this workflow yet: the deploy migration is FACT-1910, blocked on FACT-1909.

  • ci.yml sets up Node and runs every scripts/*.test.mjs.

  • README documents the new inputs and the v1.1.0 tag. Tags are never moved, so a caller gets a change only by bumping its pin.

What deliberately did NOT change

The v1 tag and the setup/test/image workflows.

Verification

  • node --test scripts/*.test.mjs: # tests 23, # pass 23, # fail 0. That is 6 existing pr-guard tests, 4 new pr-guard ::error:: tests (escaping, reportFailure, and CLI stdout for a bad body and a good body), and 13 coolify-deploy tests.
  • Sabotage runs:
    • Treating failed/cancelled as non-terminal turns 3 tests red.
    • Dropping the ::error:: write turns 2 tests red.
    • Both files restored to 23/23.
  • CLI smoke against a local mock Coolify:
    • The happy path prints queued → in_progress → finished → /health serves abc, exits 0, and writes deployment-uuid=d1 to GITHUB_OUTPUT.
    • A 404 webhook prints ::error::POST /nothere -> HTTP 404 (body redacted, 4 bytes) and exits 1, with no query string.
    • A missing URL prints ::error::Infisical did not export COOLIFY_WEBHOOK_URL.
  • actionlint 1.7.12 reports only property "workflow_sha"/"workflow_repository" is not defined on the job context. Those properties came after 1.7.12's schema; GitHub documents them. No other findings.
  • Live proof on this PR, run 44009486338 job guard / check: the script checkout used ref: 5657fe4972779fe2de10eb8d822a8c01bdb4fadf, which is job.workflow_sha resolved to this PR's merge commit, not v1. "Warn when the runner gave no workflow sha" was skipped, actions/setup-node (node 22) succeeded, and the script printed pr body ok. The self-hosted Proxmox proof comes from practical-works-factory's PR on pr-guard.yml@v1.1.0 once the tag exists.

NEEDS VERIFICATION (after a caller adopts it): the first coolify-deploy.yml@v1.1.0 run proves a real Coolify deploy end to end.

Refs: FACT-1885
Refs: FACT-1910

🤖 Generated with Claude Code

Echobob and others added 3 commits November 12, 2026 23:48
Callers pin the v1 tag, so one tag move reaches every consumer, and each job still runs on the caller's minutes.

Co-authored-by: Cursor <cursoragent@cursor.com>
A called workflow can only lower the caller's token permissions, and these
repositories default to read-only, so an image.yml caller without
packages: write fails before any step runs. The README now lists what each
workflow needs from its caller, and no longer says image.yml calls the
setup action.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…en deploys.

pr-guard.yml sets up Node 22 before its script, because the Proxmox runners
ship without node (FACT-1952), and checks the script out at job.workflow_sha,
the commit of the workflow file the caller invoked, instead of hard-coding v1.
Every pr-guard failure is also emitted as an ::error:: command (% CR LF
escaped), so the reason survives as a check annotation when a runner loses the
job log (FACT-1971).

coolify-deploy.yml now waits for Coolify's real outcome: it polls
/api/v1/deployments/<uuid> on the webhook's origin until finished, fails on
failed or cancelled, and, given health-url and expected-version, polls that URL
until it serves the version (FACT-1910). The webhook URL and token are masked.

Refs: FACT-1885
Refs: FACT-1910

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@jcotillo jcotillo added the merge:queued Hand this PR to the factory merge queue label Nov 17, 2026

@practical-bot practical-bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the current card scope (updated 2026-11-17) and the full PR diff. The shared workflows, setup action, guard/deploy scripts, tests, and README are all newly added on top of the existing v1 release. The PR correctly keeps the deploy migration itself out of this card's consumer work: no caller adopts coolify-deploy.yml here, and FACT-1910 remains the separately tracked migration.

Claim ledger:

  • PASS — node --test scripts/*.test.mjs: 23 tests, 23 passed, 0 failed.
  • VERIFIED-BY-CI — run 44009486338, head b642a37752e30e5a98ac2ff2d5912216e165d6be: guard-tests ran setup-node and all script unit tests successfully; guard / check ran the reusable guard path, setup-node, and PR body/guardrails successfully.
  • PASS — git diff --check origin/main...HEAD: no output and exit 0.
  • PASS — the PR body’s local mock smoke claims are covered by the 23 passing script tests and the checked implementation: deployment UUID output, terminal failure states, redacted HTTP errors, and optional health-version proof are exercised.
  • UNVERIFIED-BY-DESIGN — the two sabotage claims were not independently re-run because proving them requires mutating the reviewed checkout, which review mode forbids. The restored behavior is covered by the passing regression tests and exact-head CI.
  • UNVERIFIED — actionlint was not available in this workspace. The PR body reports actionlint 1.7.12 output; exact-head GitHub Actions accepted and executed both workflows. The reported job.workflow_sha/job.workflow_repository schema warning is expected for that older local schema and is not a code finding.

What is right: pr-guard.yml installs Node before invoking the shared script and checks out the workflow commit rather than a stale fixed script; reportFailure emits both stderr and a GitHub ::error:: annotation with command-data escaping; Coolify deployment polling distinguishes successful and failed terminal states, bounds transient poll misses, redacts response bodies, and optionally proves the expected version at a health URL. The workflow permissions and caller requirements are documented, and the diff is exactly 12 files / 1196 changed lines as required for this PR.

REVIEWED DIFF: base=main files=12 lines=1196

NEEDS VERIFICATION: After a caller adopts coolify-deploy.yml@v1.1.0, a real Coolify run must prove the deployment reaches finished and, when configured, the health URL serves the expected version.
NEEDS VERIFICATION: After merge/release, confirm the shared workflows are reachable at the intended v1.1.0 tag and the first consumer runs use the shared workflow source.

REVIEW VERDICT: approve

@practical-bot
practical-bot merged commit 8e60f60 into main Nov 17, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge:queued Hand this PR to the factory merge queue

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants